home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2009 February / PCWFEB09.iso / Software / Linux / SLAX 6.0.8 / slax-6.0.8.iso / slax / base / 006-devel.lzm / usr / include / arts / kplayobject.h < prev    next >
Encoding:
C/C++ Source or Header  |  2007-01-15  |  8.3 KB  |  307 lines
  1.     /*
  2.  
  3.     Copyright (C) 2001 Nikolas Zimmermann <wildfox@kde.org>
  4.  
  5.     This library is free software; you can redistribute it and/or
  6.     modify it under the terms of the GNU Library General Public
  7.     License as published by the Free Software Foundation; either
  8.     version 2 of the License, or (at your option) any later version.
  9.   
  10.     This library is distributed in the hope that it will be useful,
  11.     but WITHOUT ANY WARRANTY; without even the implied warranty of
  12.     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13.     Library General Public License for more details.
  14.  
  15.     You should have received a copy of the GNU Library General Public License
  16.     along with this library; see the file COPYING.LIB.  If not, write to
  17.     the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  18.     Boston, MA 02110-1301, USA.
  19.  
  20.     */
  21.  
  22. #ifndef KPLAYOBJECT_H
  23. #define KPLAYOBJECT_H
  24.  
  25. #include "kmedia2.h"
  26. #include "soundserver.h"
  27. #include <kurl.h>
  28. #include <qobject.h>
  29.  
  30. class KDE_EXPORT KPlayObject : public QObject
  31. {
  32. Q_OBJECT
  33. public:
  34.     KPlayObject();
  35.     KPlayObject(Arts::PlayObject playobject, bool isStream);
  36.     ~KPlayObject();
  37.  
  38.     /**
  39.       * Sets the internal Arts::PlayObject
  40.       * to @a playObject
  41.       */
  42.     void setObject(Arts::PlayObject playObject);
  43.     
  44.     /**
  45.       * Returns the internal Arts::PlayObject
  46.       */
  47.     Arts::PlayObject object();
  48.  
  49.     /**
  50.      * return true if both this != 0, and object.isNull()
  51.      *
  52.      * in essence, ((KPlayObject*)0)->isNull() will not 
  53.      * crash
  54.      **/
  55.     bool isNull();
  56.  
  57.     /**
  58.      * returns true if the internally playobject
  59.      * is used to play a stream
  60.      */
  61.         bool stream();
  62.  
  63.     /**
  64.      * Reimplemented (Arts::PlayObject Wrapper)
  65.      */
  66.     void play();
  67.     
  68.     /**
  69.      * Reimplemented (Arts::PlayObject Wrapper)
  70.      */
  71.     void seek(Arts::poTime newTime);
  72.     
  73.     /**
  74.      * Reimplemented (Arts::PlayObject Wrapper)
  75.      */
  76.     void pause();
  77.     
  78.     /**
  79.      * Reimplemented (Arts::PlayObject Wrapper)
  80.      */
  81.      
  82.     void halt();
  83.     
  84.     /**
  85.      * Reimplemented (Arts::PlayObject Wrapper)
  86.      */
  87.     QString description();
  88.     
  89.     /**
  90.      * Reimplemented (Arts::PlayObject Wrapper)
  91.      */
  92.     Arts::poTime currentTime();
  93.     
  94.     /**
  95.      * Reimplemented (Arts::PlayObject Wrapper)
  96.      */
  97.     Arts::poTime overallTime();
  98.     
  99.     /**
  100.      * Reimplemented (Arts::PlayObject Wrapper)
  101.      */
  102.     Arts::poCapabilities capabilities();
  103.     
  104.     /**
  105.      * Reimplemented (Arts::PlayObject Wrapper)
  106.      */
  107.     QString mediaName();
  108.     
  109.     /**
  110.      * Reimplemented (Arts::PlayObject Wrapper)
  111.      */
  112.     Arts::poState state();
  113.  
  114. private:
  115.     Arts::PlayObject m_playObject;
  116.     bool m_isStream;
  117. };
  118.  
  119.  
  120.  
  121. namespace KDE {
  122.  
  123. class PlayObjectFactory;
  124.  
  125. /**
  126.   * This class acts as a general interface to the KDE multimedia framework.
  127.   * You basically point the Playobject to an URL and say "play", and it will
  128.   * automatically decode and play and / or display the file or stream.
  129.   * For non-local media, it will make extensive use of KIOInputStream to
  130.   * directly play the content from the remote location without having to
  131.   * download it to a temporary local file first.
  132.   *
  133.   * A KDE::PlayObject is never created directly with new, but only through
  134.   * a KDE::PlayObjectFactory.
  135.   *
  136.   * Basically, it is used like this:
  137.   * \code
  138.   * KArtsDispatcher dispatcher;
  139.   * KArtsServer server;
  140.   * KDE::PlayObjectFactory factory( server.server() );
  141.   * KDE::PlayObject* playobj = factory.createPlayObject( someURL, true );
  142.   * playobj->play();
  143.   * \endcode
  144.   *
  145.   * Internally, the KDE::PlayObject acts as a wrapper for an Arts::PlayObject.
  146.   *
  147.   * Special care needs to be taken for non-local media. In general, you
  148.   * cannot safely figure out the mimetype of the remote media content, by
  149.   * looking at the URL alone. You need to download some data to analyze
  150.   * the content. Since KDE::PlayObject is only a wrapper for an
  151.   * Arts::PlayObject, and an Arts::PlayObject needs to know the mimetype
  152.   * of the data it plays in order to pick the correct decoder, one cannot
  153.   * directly create an Arts::PlayObject and attach it to a stream. Therefore,
  154.   * the following approach is used.
  155.   *
  156.   * Whenever a the factory creates a KDE::PlayObject for a non-local content,
  157.   * it first generates a so called "Proxy" Playobject. This is a
  158.   * KDE::PlayObject that does not contain a real Arts::PlayObject yet.
  159.   * As soon as you invoke the play() method, a connection to the media
  160.   * source is made, and as soon as the mimetype is known, the appropriate
  161.   * Arts::PlayObject is created.
  162.   *
  163.   * This has some side effects that developers need to be aware of:
  164.   * Until the real Arts::PlayObject got created,
  165.   * - the capabilities() method returns "zero" capabilities,
  166.   * - description() and mediaName() will return a null QString,
  167.   * - currentTime() and overallTime() will return "zero",
  168.   * - despite the fact that isNull() returns "false", object().isNull()
  169.   *   will return "true". If you need to directly access methods of the
  170.   *   internal Arts::PlayObject, be sure to use object().isNull() to guard
  171.   *   your access.
  172.   *
  173.   * A KDE::PlayObject will emit the signal playObjectCreated()
  174.   * as soon as the real internal Arts::PlayObject got created. This is also
  175.   * true for local media files. So you can generally connect to this signal
  176.   * and act on it if your application needs to know about the real capabilities
  177.   * of the Arts::PlayObject.
  178.   *
  179.   * However, KDE::PlayObject will try to act reasonable on calls to play(),
  180.   * halt(), pause() and state(). If you call play() and then pause() 
  181.   * before the connection to the media source was established, it will 
  182.   * not start playing once the connection got established. Calling halt()
  183.   * will cancel the connection process. KDE::PlayObject will maintain
  184.   * an internal state variable, and calling state() will return this
  185.   * internal state until the real Arts::PlayObject got created, afterwards
  186.   * the state of the Arts::PlayObject will be returned.
  187.   */
  188. class KDE_EXPORT PlayObject : public QObject
  189. {
  190. Q_OBJECT
  191. public:
  192.     ~PlayObject();
  193.  
  194.     /**
  195.       * Returns the internal Arts::PlayObject
  196.       */
  197.     Arts::PlayObject object();
  198.  
  199.     /**
  200.      * return true if this != 0.
  201.      *
  202.      * in essence, ((KDE::PlayObject*)0)->isNull() will not 
  203.      * crash
  204.      **/
  205.     bool isNull();
  206.  
  207.     /**
  208.      * returns "true" if the content to play is delivered as a stream.
  209.      */
  210.         bool stream();
  211.  
  212.     /**
  213.      * causes the PlayObject to start the play back.
  214.      */
  215.     void play();
  216.     
  217.     /**
  218.      * causes the PlayObject to skip to the time @p newTime. 
  219.      * You don't need to stop or restart the play back after calling seek.
  220.      */
  221.     void seek(Arts::poTime newTime);
  222.     
  223.     /**
  224.      * causes the PlayObject to pause play back immediately. It will not
  225.      * restart until you call play(). This also works on streams, the
  226.      * connection to the media source will be maintained while the 
  227.      * PlayObject is paused.
  228.      */
  229.     void pause();
  230.     
  231.     /**
  232.      * immediately stops the play back and resets the media to the
  233.      * start of the content. If playing from a stream, halt() causes
  234.      * the connection to be canceled.
  235.      */
  236.      
  237.     void halt();
  238.     
  239.     /**
  240.      * Reimplemented (Arts::PlayObject Wrapper)
  241.      */
  242.     QString description();
  243.     
  244.     /**
  245.      * Reimplemented (Arts::PlayObject Wrapper)
  246.      */
  247.     Arts::poTime currentTime();
  248.     
  249.     /**
  250.      * Reimplemented (Arts::PlayObject Wrapper)
  251.      */
  252.     Arts::poTime overallTime();
  253.     
  254.     /**
  255.      * returns the capabilities of the PlayObject. The return value is
  256.      * a binary OR of Arts::capSeek and Arts::capPause, or 0.
  257.      */
  258.     Arts::poCapabilities capabilities();
  259.     
  260.     /**
  261.      * Reimplemented (Arts::PlayObject Wrapper)
  262.      */
  263.     QString mediaName();
  264.     
  265.     /**
  266.      * returns the internal state of the PlayObject. The state can be
  267.      * either Arts::posIdle, Arts::posPaused or Arts::posPlaying. A
  268.      * PlayObject in state Arts::posIdle is stopped. Once you call
  269.      * play(), the state changes to Arts::posPlaying. pause() causes
  270.      * the PlayObject to change to Arts::posPaused.
  271.      */
  272.     Arts::poState state();
  273.  
  274. signals:
  275.     /**
  276.      * this signal is emitted as soon as the internal Arts::PlayObject
  277.      * is created and ready to play. It is granted that the Arts::PlayObject
  278.      * has not started playing, but KDE::PlayObject will call
  279.      * object().play() immediately after emitting this signal, so you
  280.      * need not do it yourself.
  281.      */
  282.     void playObjectCreated();
  283.  
  284. private slots:
  285.     void attachPlayObject( Arts::PlayObject );
  286.  
  287. private:
  288.     Arts::PlayObject m_playObject;
  289.     bool m_isStream;
  290.  
  291.     struct PrivateData;
  292.     PrivateData* d;
  293.  
  294.     /* private constructors, to prevent instantiation and copying */
  295.     PlayObject();
  296.     PlayObject( const PlayObject& ) : QObject() {};
  297.     PlayObject(Arts::PlayObject playobject, bool isStream);
  298.     PlayObject( Arts::SoundServerV2 server, const KURL& url, bool isStream, bool createBUS );
  299.  
  300.     friend class KDE::PlayObjectFactory;
  301.  
  302. };
  303.  
  304. }
  305.  
  306. #endif
  307.